---- Entities Guide ----

Entities are a special type of value that represent components within the simulation
or components used to encapsulate other components. Entities can have one or more
attributes which can be accessed using the 'access' operator, '.', in the following
manner: <entity>.<attribute>
Example:
  "target.preferences.cohesion"

An access operation is handled as an expression and as such, can either ver resolved
into a value or an effect. A value returned by an access operator can be of any of
the supported types: numbers, booleans, strings or other entities. Certain attributes
are function-like and expect one or more parameters, and they should be invoked in
this manner: <entity>.<attribute>(<parameters>)

Here's a list of currently supported entities and their attributes:

- CELL:
  This type of entity encapsulates a a fixed area on the world map and has general
  information about that area's characteristics: longitude, latitude, altitude, temperature,
  rainfall, present biomes, etc.
  Properties:
  - biome_trait_presence:
    Attribute function that returns the presence of a specific
    biome trait within a cell as a NUMERIC value between 0 and 1.
    Examples: "cell.biome_trait_presence(wood)", "target.cell.biome_trait_presence(sea)"

- GROUP:
  This type of entity encapsulates a population group occupying a cell on the surface
  of the map and contains information about characteristics like: population, cultural
  attributes, influences, etc.
  Properties:
  - cell:
    Attribute that returns the cell entity where this group is located.
    Examples: "group.cell", "target.cell"

- POLITY:
  This type of entity encapsulates a polity in the planet and information about it's
  culture, territory, factions, etc.
  Properties:
  - type:
    Attribute that returns the type of polity. Current available type: tribe
    Example: "polity.type == tribe"
  - get_random_group:
    Attribute that selects and returns a random group entity that falls within the
    polity's prominence sphere.
    Example: "polity.get_random_group()"
  - dominant_faction:
    Attribute that returns the current dominant faction entity
    Example: "target == polity.dominant_faction"
  - transfer_influence:
    Attribute function that transfers influence between to of the polity's factions
    Example: "polity.transfer_influence(source_faction, target_faction, influence_to_transfer)"

- AGENT:
  This type of entity encapsulates any individual that is or was present within the
  simulation. That includes faction leaders.
  Properties:
  - charisma:
    Attribute that returns an agent's charisma level as a value between 0 and 1.
    Examples: "leader.charisma < 0.5"
  - wisdom:
    Attribute that returns an agent's wisdom level as a value between 0 and 1.
    Examples: "0.3 >= current_leader.wisdom"

- FACTION:
  This type of entity encapsulates any faction that can be part of a polity. most
  decisions have a faction as target entity.
  Properties:
  - type:
    Attribute that returns the type of faction. Current available type: clan
    Example: "target.type == clan"
  - administrative_load:
    Attribute that returns the faction's current administrative load.
    Examples: "target.administrative_load > 100000"
  - influence:
    Attribute that returns the faction's influence on the containing polity.
    Examples: "faction.influence <= 0.6"
  - preferences:
    Attribute that returns an entity containing all the faction's cultural preferences.
    Examples: "target.preferences.authority <= 0.5"
  - trigger_decision:
    Attribute function that will trigger a decision referenced by the given id.
    The function needs to receive as extra parameters all of the parameters needed to
    execute the given decision
    Examples: "dominant_faction.trigger_decision(influence_demanded_from_clan, target)"
  - split:
    Attribute function that will trigger a faction to split a new faction from
    itself. The function expects two parameters: a group to become the new faction's
    core, and a percentage of influence (as a value between 0 and 1) to transfer from
    the parent faction.
    Examples: "target.split(new_core_group, 0.5)"
  - group_can_be_core:
    Attribute function that will return the BOOLEAN value, "True", if a specific group
    entity can become the core of a faction. "False" if otherwise.
    Examples: "dominant_faction.group_can_be_core(chossen_group)"
  - relationship:
    Attribute function that will return a NUMERIC value corresponding to the current
    relationship value between this faction and the faction given as parameter.
    Examples: "target.relationship(dominant_faction)"
  - set_relationship:
    Attribute function that will update the relationship value between this faction
    and the faction given as first parameter, using the NUMERIC value given in the
    second parameter.
    Examples: "dominant_faction.set_relationship(target, input_value / 2)"
  - leader:
    Attribute that returns the faction's current leader as an agent entity.
    Examples: "faction.leader.charisma"
  - polity:
    Attribute that returns the polity entity to which this faction belongs to.
    Examples: "faction.polity.type == tribe"
  - core_group:
    Attribute that returns the core of this faction as a group entity.
    Examples: "target.core_group != new_core_group"
